---
title: Avatar
description: An image element with a fallback for representing the user.
links:
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/data-display/avatar.mdx?plain=1
---

<ComponentPreview
  name="avatar/demos/default"
  preview={`<Avatar src="https://github.com/mehdibha.png" alt="@mehdibha" fallback="M" />
  <Avatar src="https://githubbb.com/mehdibha.png" alt="@mehdibha" fallback="M" /> // invalid URL`}
/>

## Installation

```package-install
npx shadcn@latest add @dotui/avatar
```

## Anatomy

```tsx
import { Avatar } from "@/components/core/avatar";

<Avatar src=".." alt=".." />;
```

```tsx
import {
  AvatarFallback,
  AvatarImage,
  AvatarPlaceholder,
  AvatarRoot,
} from "@/components/core/avatar";

<AvatarRoot>
  <AvatarImage src=".." alt=".." />
  <AvatarFallback>..</AvatarFallback>
  <AvatarPlaceholder />
</AvatarRoot>;
```

## Options

### Shape

`Avatar` can be either a circle or a square using the `shape` prop.

<ComponentPreview
  name="avatar/demos/shape"
  preview={`<Avatar shape="square" />
<Avatar shape="circle" />`}
/>

### Size

Use the `size` prop to control the size of the `Avatar`. The default variant is `md`.

<ComponentPreview
  name="avatar/demos/sizes"
  preview={`<Avatar size="sm" />
  <Avatar size="md" />
  <Avatar size="lg" />`}
/>

## Composition

If you need to customize things further, you can drop down to the composition level.

<ComponentPreview
  name="avatar/demos/composition"
  preview={`<AvatarRoot>
    <AvatarImage src="https://github.com/mehdibha.png" alt="@mehdibha" />
    <AvatarFallback>M</AvatarFallback>
    <AvatarPlaceholder>
      <UserIcon className="size-5" />
    </AvatarPlaceholder>
  </AvatarRoot>`}
/>

## API Reference

`Avatar` accepts all image attributes.

| Prop       | Type                   | Default    | Description                                                    |
| ---------- | ---------------------- | ---------- | -------------------------------------------------------------- |
| `shape`    | `'circle' \| 'square'` | `'circle'` | The shape of the avatar.                                       |
| `size`     | `'sm' \| 'md' \| 'lg'` | `'md'`     | The size of the avatar.                                        |
| `fallback` | `ReactNode`            | -          | The fallback element to render when an image is not available. |
